ohm-js

What is ohm-js?

Ohm is a parser generator for building languages and interpreters. It provides a way to define grammars and parse text according to those grammars. Ohm is particularly useful for creating domain-specific languages, interpreters, and compilers.

What are ohm-js's main functionalities?

Defining Grammars

This feature allows you to define a grammar using Ohm's syntax. The example defines a simple arithmetic grammar that can parse expressions involving addition, subtraction, multiplication, and division.

const ohm = require('ohm-js');
const grammar = ohm.grammar(`
  Arithmetic {
    Exp = AddExp
    AddExp = AddExp "+" MulExp  -- plus
           | AddExp "-" MulExp  -- minus
           | MulExp
    MulExp = MulExp "*" PriExp  -- times
           | MulExp "/" PriExp  -- divide
           | PriExp
    PriExp = "(" Exp ")"        -- paren
           | number
    number = digit+
  }
`);

Parsing Input

Once a grammar is defined, you can use it to parse input strings. This example parses an arithmetic expression and checks if the parsing succeeded.

const input = '3 + 5 * (10 - 4)';
const matchResult = grammar.match(input);
if (matchResult.succeeded()) {
  console.log('Parsing succeeded!');
} else {
  console.log('Parsing failed.');
}

Semantic Actions

Ohm allows you to define semantic actions that can be performed on the parse tree. This example defines an 'eval' operation to evaluate arithmetic expressions parsed by the grammar.

const semantics = grammar.createSemantics().addOperation('eval', {
  Exp: function(e) { return e.eval(); },
  AddExp_plus: function(a, _, b) { return a.eval() + b.eval(); },
  AddExp_minus: function(a, _, b) { return a.eval() - b.eval(); },
  MulExp_times: function(a, _, b) { return a.eval() * b.eval(); },
  MulExp_divide: function(a, _, b) { return a.eval() / b.eval(); },
  PriExp_paren: function(_1, e, _2) { return e.eval(); },
  number: function(digits) { return parseInt(this.sourceString, 10); }
});
const result = semantics(matchResult).eval();
console.log(result);

Other packages similar to ohm-js

pegjs

PEG.js is a simple parser generator for JavaScript that produces fast parsers with excellent error reporting. Like Ohm, it allows you to define grammars and parse text, but it uses Parsing Expression Grammars (PEG) instead of Ohm's custom syntax.

antlr4

ANTLR (Another Tool for Language Recognition) is a powerful parser generator for reading, processing, executing, or translating structured text or binary files. It is more feature-rich and supports multiple target languages, making it more versatile than Ohm, but also more complex to use.

nearley

Nearley is a simple, fast, and powerful parser toolkit for JavaScript. It uses Earley parsing, which can handle more complex grammars than PEG-based parsers like PEG.js. Nearley is more flexible but can be more difficult to use for simple grammars compared to Ohm.

README

Ohm

Ohm is a library and domain-specific language for parsing and pattern matching. You can use it to parse custom file formats, transform complex data structures, and quickly build parsers, interpreters, and compilers for programming languages. The Ohm language is based on parsing expression grammars (PEGs), which are a formal way of describing syntax, similar to regular expressions and context-free grammars. The Ohm library provides a JavaScript interface (known as Ohm/JS) for creating parsers, interpreters, and more from the grammars you write.

Like its older sibling OMeta, Ohm supports object-oriented grammar extension and allows pattern matching on structured data as well as strings. One thing that distinguishes Ohm from other parsing tools is that it completely separates grammars from semantic actions. In Ohm, a grammar defines a language, and semantic actions specify what to do with valid inputs in that language. Semantic actions are written in the host language -- e.g., for Ohm/JS, the host language is JavaScript. Ohm grammars, on the other hand, work without modification in any host language. This separation improves modularity, and makes both grammars and semantic actions easier to read and understand. Currently, JavaScript is the only host language, but as the API stabilizes, we hope to have implementations for other languages.

Learn more about the Ohm philosophy here.

Getting Started

The easiest way to get started with Ohm is to play with one of the following examples on JSFiddle:

• Basic parsing example
• Arithmetic example with semantics

Resources

• There's no tutorial yet, but the math example is extensively commented and is probably the best place to start.
• Examples
• Documentation
• Ask questions and give us feedback in the Ohm Google Group.

Installation

For use in the browser:

• Download ohm.js (development version, with full source and comments) or ohm.min.js (a minified version for faster page loads).

• Add a new script tag to your page, and set the src attribute to the path of the file you just downloaded. E.g.:

  <script src="ohm.js"></script>
  

  This creates a global variable named ohm.

If you are using Node.js, you can just install the ohm-js package using npm:

npm install ohm-js

This will install Ohm in the local node_modules folder. Use require to access it from a Node script:

var ohm = require('ohm-js');

Basics

Defining Grammars

To use Ohm, you need a grammar that is written in the Ohm language. The grammar provides a formal definition of the language or data format that you want to parse. There are a few different ways you can define an Ohm grammar:

• Define the grammar directly in a JavaScript string and instantiate it using ohm.grammar():

  var myGrammar = ohm.grammar('MyGrammar { greeting = "Hello" | "Hola" }');
  

  This is the simplest option, but it can be awkward to define larger grammars this way.

• Recommended when running in the browser: Embed the grammar source inside its own <script> tag with the attribute type="text/ohm-js", and instantiate it using ohm.grammarFromScriptElement():

  <script type="text/ohm-js">
    MyGrammar {
      greeting = "Hello" | "Hola"
    }
  </script>
  <script>
    var myGrammar = ohm.grammarFromScriptElement();
  </script>
  

• Recommended with Node.js: Define the grammar in a separate file, read the file's contents and instantiate it using ohm.grammar(contents):

  In myGrammar.ohm:

    MyGrammar {
      greeting = "Hello" | "Hola"
    }
  

  In JavaScript:

  var fs = require('fs');
  var contents = fs.readFileSync('myGrammar.ohm');
  var myGrammar = ohm.grammar(contents);
  

For more information, see Instantiating Grammars in the API reference.

Using Grammars

Once you've instantiated a grammar object, use the grammar's match() method to recognize input:

var userInput = 'Hello';
var m = myGrammar.match(userInput);
if (m.succeeded()) {
  console.log('Greetings, human.');
} else {
  console.log("That's not a greeting!");
}

The result is a MatchResult object. You can use the succeeded() and failed() methods to see whether the input was recognized or not.

For more information, see the main documentation.

Debugging

Ohm has two tools to help you debug grammars: a text trace, and a graphical visualizer. The visualizer is still under development (i.e., it might be buggy!) but it can still be useful.

You can try the visualizer online, or if you have an Ohm checkout, open visualizer/index.html in your web browser.

To see the text trace for a grammar g, just use the g.trace() method instead of g.match. It takes the same arguments, but instead of returning a MatchResult object, it returns a Trace object -- calling its toString method returns a string describing all of the decisions the parser made when trying to match the input. For example, here is the result of g.trace('ab').toString() for the grammar G { start = letter+ }:

ab         ✓ start ⇒  "ab"
ab           ✓ letter+ ⇒  "ab"
ab             ✓ letter ⇒  "a"
ab                 ✓ lower ⇒  "a"
ab                   ✓ Unicode {Ll} character ⇒  "a"
b              ✓ letter ⇒  "b"
b                  ✓ lower ⇒  "b"
b                    ✓ Unicode {Ll} character ⇒  "b"
               ✗ letter
                   ✗ lower
                     ✗ Unicode {Ll} character
                   ✗ upper
                     ✗ Unicode {Lu} character
                   ✗ unicodeLtmo
                     ✗ Unicode {Ltmo} character
           ✓ end ⇒  ""

Publishing Grammars

If you've written an Ohm grammar that you'd like to share with others, see our suggestions for publishing grammars.

Contributing to Ohm

All you need to get started:

git clone https://github.com/cdglabs/ohm.git
cd ohm
npm install

NOTE: We recommend using the latest Node.js stable release (>=0.12.1) for development. Some of the JSDOM-based tests are flaky on io.js, and other tests will reliably fail on older versions of Node.

Some useful scripts

• npm test runs the unit tests.
• npm run test-watch re-runs the unit tests every time a file changes.
• npm run build builds dist/ohm.js and dist/ohm.min.js, which are stand-alone bundles that can be included in a webpage.
• When editing Ohm's own grammar (in src/ohm-grammar.ohm), run npm run bootstrap to re-build Ohm and test your changes.

Before submitting a pull request, be sure to add tests, and ensure that npm run prepublish runs without errors.